Note Allocator Functions: Note Channel Allocation and Use19

The functions described in this section create, manipulate, and get information about note channels.

NANewNoteChannel

The NANewNoteChannel function requests a new note channel with the qualities described in the noteRequest structure.



 
pascal ComponentResult NANewNoteChannel( 

                     NoteAllocator na, 

                     NoteRequest *noteRequest,

                     NoteChannel *outChannel);

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.
noteRequest: A pointer to a note request structure.
outChannel: On exit, a pointer to an identifier for a new note channel or NIL if the function fails to create a note channel.
function result: A result code.

DISCUSSION

The caller may request an instrument that is not currently allocated to a part. In that case, the NANewNoteChannel function may return a value in outChannel , even though the request cannot initially be satisfied. The note channel may become valid at a later time, as other note channels are released or other music components are registered.

The NANewNoteChannel function searches all available music components for the instrument that best matches the specifications in the ToneDescripion structure that is contained within the noteRequest parameter.

If an error occurs, the note noteChannel will be initialized to nil .

NANewNoteChannelFromAtomicInstrument

You can use the NANewNoteChannelFromAtomicInstrument function to request a new note channel for an atomic instrument.



 
extern pascal ComponentResult NANewNoteChannelFromAtomicInstrument(

                     NoteAllocator na,

                     AtomicInstrumentPtr instrument,

                     long flags,

                     NoteChannel *outChannel)

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.
instrument: A pointer to the atomic instrument. This may be a dereferenced locked QT atom container.
flags: These flags specify details of initializing a part with an atomic instrument. Flags for Setting Atomic Instruments
outChannel: On exit, a pointer to an identifier for a new note channel or nil if the function fails to create a note channel.
function result: A result code.

DISCUSSION

The NANewNoteChannelFromAtomicInstrument function takes a note allocator identifier in the na parameter and a pointer to the atomic instrument you are requesting a new channel for in the instrument parameter. Among other things, you can specify how to handle the expanded sample with the flags parameter.

The function returns the note channel allocated for the instrument in the outChannel parameter or nil if an error occurs.

NADisposeNoteChannel

The NADisposeNoteChannel function deletes the specified note channel.



 
pascal ComponentResult NADisposeNoteChannel(

                     NoteAllocator na, 

                     NoteChannel noteChannel);

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.
noteChannel: Note channel to be disposed. You obtain the note channel identifier from the NANewNoteChannel or the NANewNoteChannelFromAtomicInstrument function.
function result: A result code.

NAGetNoteChannelInfo

The NAGetNoteChannelInfo function returns the index of the music component for the allocated channel and its part number on that music component.



 
pascal ComponentResult NAGetNoteChannelInfo(

                     NoteAllocator na, 

                     NoteChannel noteChannel, 

                     long *index, 

                     long *part)

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.
noteChannel: Note channel to get information about. You obtain the note channel identifier from the NANewNoteChannel or the NANewNoteChannelFromAtomicInstrument function.
*index: Music component index.
*part: Music component part pointer.
function result: A result code.

DISCUSSION

The NAGetNoteChannelInfo function allows direct access to the music component allocated to the note channel by the note allocator. The index returned will be invalid if music components are subsequently registered or unregistered.

NAGetIndNoteChannel

The NAGetIndNoteChannel function returns the number of note channels handled by the specified note allocator instance. It can also return a requested note channel.



 
extern pascal ComponentResult NAGetIndNoteChannel(

                     NoteAllocator na,

                     long index,

                     NoteChannel *nc,

                     long *seed)

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.
index: The index of the note channel. If zero, the result is still the number of note channels, but *nc is not filled out.
nc: The note channel requested.
seed: A number that changes on successive calls if anything significant changes about a note channel--for example, if the note channel has been reallocated or released.
function result: Positive results are the index count; negative results are error codes.

DISCUSSION

To get a count of the note channels, pass the NAGetIndNoteChannel function 0 in the index parameter. To get a specific note channel, pass the index value returned by a previous call to NAGetIndNoteChannel.

NAUseDefaultMIDIInput

The NAUseDefaultMIDIInput function defines an entry point to service external MIDI device events. This routine, in turn, calls the QT MIDI components to query them. NAGetMIDIPorts is the correct call for users to make. Users should not call QTMIDI .



 
pascal ComponentResult NAUseDefaultMIDIInput (

                     NoteAllocator na, 

                     MusicMIDIReadHookUPP readHook,

                     long refCon, 

                     unsigned long flags)

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.
readHook: Process pointer for MIDI service.
refcon: Contains a reference constant value. The Movie Toolbox passes this reference constant to your error-notification function each time it calls your function.
flags: Must contain zero.
function result: A result code.

DISCUSSION

The NAUseDefaultMIDIInput function specifies an application's procedure to service external MIDI events. The specified application's procedure call, defined by readHook , will be called when the external default MIDI device has incoming MIDI data for the application.

NALoseDefaultMIDIInput

The NALoseDefaultMIDIInput function removes the external default MIDI service procedure call, if previously defined by NAUseDefaultMIDIInput . This routine, in turn, calls the QT MIDI components to query them. NAGetMIDIPorts is the correct call for users to make. Users should not call QTMIDI .



 
pascal ComponentResult NALoseDefaultMIDIInput (NoteAllocator na);

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.
function result: A result code or -1 if a default MIDI device was not in use.

NAPrerollNoteChannel

The NAPrerollNoteChannel function attempts to reallocate the note channel, if it was invalid previously.



 
pascal ComponentResult NAPrerollNoteChannel( 

                     NoteAllocator na,

                     NoteChannel noteChannel);

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.
noteChannel: Note channel to be re-allocated. You obtain the note channel identifier from the NANewNoteChannel or the NANewNoteChannelFromAtomicInstrument function.
function result: A result code.

DISCUSSION

The NAPrerollNoteChannel function attempts to reallocate the note channel, if it was invalid previously. It could have been invalid if there were no available voices on any registered music components when the note channel was created.

NAUnrollNoteChannel

The NAUnrollNoteChannel function marks a note channel as available to be stolen.



 
pascal ComponentResult NAUnrollNoteChannel( 

                     NoteAllocator na,

                     NoteChannel noteChannel);

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.
noteChannel: Note channel to be unrolled. You obtain the note channel identifier from the NANewNoteChannel or the NANewNoteChannelFromAtomicInstrument function.
function result: A result code.

NAResetNoteChannel

The NAResetNoteChannel function turns off all currently "on" notes on the note channel, and resets all controllers to their default values.



 
pascal ComponentResult NAResetNoteChannel( 

                     NoteAllocator na, 

                     NoteChannel noteChannel);

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.
noteChannel: The note channel to reset. You obtain the note channel identifier from the NANewNoteChannel or the NANewNoteChannelFromAtomicInstrument function.
function result: A result code.

DISCUSSION

The NAResetNoteChannel function resets the specified note channel by turning "off" any note currently playing. All controllers are reset to their default state. The effects of the NAResetNoteChannel call are propagated down to the allocated part within the appropriate music component.

NASetNoteChannelVolume

The NASetNoteChannelVolume function sets the volume on the specified note channel.



 
pascal ComponentResult NASetNoteChannelVolume(

                     NoteAllocator na, 

                     NoteChannel noteChannel,

                     Fixed volume);

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.
noteChannel: The note channel to reset. You obtain the note channel identifier from the NANewNoteChannel or the NANewNoteChannelFromAtomicInstrument function.
volume: The volume to set the channel to. The value is a fixed 16.16 number.

DISCUSSION

The NASetNoteChannelVolume function sets the volume for the note channel, which is different than a controller 7 (volume controller) setting.

Both volume settings allow fractional values of 0.0 to 1.0. Each value will modify the other. For example, a controller value of 0.5 and a NASetNoteChannelVolume value of 0.5 result in a 0.25 volume level.

NASetNoteChannelBalance

The NASetNoteChannelBalance function modifies the pan controller setting for a note channel.



 
extern pascal ComponentResult NASetNoteChannelBalance(

                     NoteAllocator na,

                     NoteChannel noteChannel,

                     long balance)

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.
noteChannel: The note channel to be balanced. You obtain the note channel identifier from the NANewNoteChannel or the NANewNoteChannelFromAtomicInstrument function.
balance: Specifies how to modify the pan controller setting. Valid values are between -128 to 128 for left to right balance.
function result: A result code.

NASetNoteChannelSoundLocalization

The NASetNoteChannelSoundLocalization function passes sound localization data to a note channel.



 
extern pascal ComponentResult NASetNoteChannelSoundLocalization(

                     NoteAllocator na,

                     NoteChannel noteChannel,

                     Handle data)

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.
noteChannel: The note channel to pass the data to. You obtain the note channel identifier from the NANewNoteChannel or the NANewNoteChannelFromAtomicInstrument function.
data: Sound localization data.
function result: A result code.

NAPlayNote

The NAPlayNote function plays a note with a specified pitch and velocity on the specified note channel.



 
pascal ComponentResult NAPlayNote( 

                     NoteAllocator na, 

                     NoteChannel noteChannel,

                     long pitch, 

                     long velocity);

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.
noteChannel: The note channel to play the note. You obtain the note channel identifier from the NANewNoteChannel or the NANewNoteChannelFromAtomicInstrument function.
pitch: The pitch at which to play the note. You can specify values as integer pitch values (0-127 where 60 is middle C) or fractional pitch values (256 (0x1.00 ) through 32767 (0x7F.FF )).
velocity: The velocity with which the key is struck. A value of 0 is silence; a value of 127 is maximum force.
function result: A result code.

DISCUSSION

The NAPlayNote function plays a specific note. If the pitch is a number from 0 to 127, then it is the MIDI pitch, where 60 is middle C. If the pitch is a positive number above 65535, then the value is a fixed-point pitch value. Thus, microtonal values may be specified. The range 256 (0x01.00 ) through 32767 (0x7F.FF ), and all negative values, are not defined, and should not be used.

The velocity refers to how hard the key was struck (if performed on a keyboard-instrument). Typically, this translates directly to volume, but on many synthesizers this also subtly alters the timbre of the tone.

NAGetController

You use the NAGetController function to get the controller settings for a note channel.



 
pascal ComponentResult NAGetController (

                     NoteAllocator na, 

                     NoteChannel noteChannel,

                     long controllerNumber, 

                     long *controllerValue);

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.
noteChannel: Note channel for which to get controller settings. You obtain the note channel identifier from the NANewNoteChannel or the NANewNoteChannelFromAtomicInstrument function.
controllerNumber: The controller for which to get settings. For valid values, see "Controller Numbers" .
controllerValue: The returned value for the controller setting, typically 0 (0x00.00 ) to 32767 (0x7F.FF )

RESULT CODES

To be provided.

NASetController

The NASetController function changes the controller setting on a note channel to a specified value.



 
pascal ComponentResult NASetController 

                     (NoteAllocator na, 

                     NoteChannel noteChannel,

                     long controllerNumber, 

                     long controllerValue);

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.
noteChannel: Note channel on which to change controller. You obtain the note channel identifier from the NANewNoteChannel or the NANewNoteChannelFromAtomicInstrument function.
controllerNumber: The controller to set. For valid values, see "Controller Numbers" .
controllerValue: Value for controller setting, typically 0 (0x00.00 ) to 32767 (0x7F.FF )

RESULT CODES

To be provided.

NAGetKnob

Use the NAGetKnob function to get the value of a knob for a given note channel.



 
extern pascal ComponentResult NAGetKnob(

                     NoteAllocator na,

                     NoteChannel noteChannel,

                     long knobNumber,

                     long *knobValue)

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.
noteChannel: The note channel whose knob value you want to get. You obtain the note channel identifier from the NANewNoteChannel or the NANewNoteChannelFromAtomicInstrument function.
knobNumber: The index or ID of the knob whose value you want to get.
knobValue: On exit, the value of the knob.
function result: A result code.

DISCUSSION

The NAGetKnob function takes a note allocator component identifier in the na parameter, a note channel identifier in the noteChannel parameter, and the knob index or ID in the knobNumber parameter. It returns, in the knobValue parameter, a pointer to the current value of the knob.

NASetKnob

The NASetKnob function sets a note channel knob to a particular value.



 
pascal ComponentResult NASetKnob(

                     NoteAllocator na, 

                     NoteChannel noteChannel, 

                     long knobNumber,

                     long knobValue)

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.
noteChannel: Note channel on which to set the knob value. You obtain the note channel identifier from the NANewNoteChannel or the NANewNoteChannelFromAtomicInstrument function.
knobNumber: Index or ID of the knob to be set.
knobValue: Value to set knob to.
function result: A result code.

DISCUSSION

The NASetKnob function takes a note allocator component identifier in the na parameter, a note channel identifier in the noteChannel parameter, the knob ID or index in the knobNumber parameter, and a knob value in the knobValue parameter. It sets the specified knob to the given value.

NAFindNoteChannelTone

The NAFindNoteChannelTone function locates the instrument that best fits a requested tone description for a specific channel.



 
pascal ComponentResult NAFindNoteChannelTone( 

                     NoteAllocator na, 

                     NoteChannel noteChannel,

                     ToneDescription *td, 

                     long *instrumentNumber);

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.
noteChannel: The note channel for which you want an instrument. You obtain the note channel identifier from the NANewNoteChannel or the NANewNoteChannelFromAtomicInstrument function.
*td: Description for instrument fit.
*instrumentNumber: On exit, the number of the instrument that best fits the tone description.
function result: A result code.

NASetInstrumentNumber

The NASetInstrumentNumber function initializes a synthesizer part with the specified instrument.



 
pascal ComponentResult NASetInstrumentNumber( 

                     NoteAllocator na, 

                     NoteChannel noteChannel, 

                     short instrumentNumber);

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.
noteChannel: Note channel to initialize with the instrument. You obtain the note channel identifier from the NANewNoteChannel or the NANewNoteChannelFromAtomicInstrument function.
instrumentNumber: Number of the instrument to initialize the part with. This number is unique to each synthesizer. General MIDI synthesizers all share the range 1-128 and 16365 to kLastDrumKit .
function result: A result code.

NASetInstrumentNumberInterruptSafe

You can use the NASetInstrumentNumberInterruptSafe function to initialize a synthesizer part with the specified instrument during interrupt time.



 
extern pascal ComponentResult NASetInstrumentNumberInterruptSafe(

                     NoteAllocator na,

                     NoteChannel noteChannel,

                     long instrumentNumber);

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.
noteChannel: Note channel to initialize with the instrument. You obtain the note channel identifier from the NANewNoteChannel or the NANewNoteChannelFromAtomicInstrument function.
instrumentNumber: Number of the instrument to initialize the part with.
function result: A result code.

DISCUSSION

If the instrument is not already loaded when you call the NASetInstrumentNumberInterruptSafe function, you have to wait for the next call to the NATask function for the instrument to become available.

NASetAtomicInstrument

The NASetAtomicInstrument function initializes a synthesizer part with an atomic instrument.



 
extern pascal ComponentResult NASetAtomicInstrument(

                     NoteAllocator na,

                     NoteChannel noteChannel,

                     AtomicInstrumentPtr instrument,

                     long flags)

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.
noteChannel: The note channel to apply the atomic instrument to. You obtain the note channel identifier from the NANewNoteChannel or the NANewNoteChannelFromAtomicInstrument function.
instrument: A pointer to the atomic instrument. This can be a locked, dereferenced atomic instrument.
flags: Details about how to initialize the part. For a description of the flags, see "Flags for Setting Atomic Instruments" .
function result: A result code.

NASendMIDI

Use the NASendMIDI function to send a MIDI music packet to a synthesizer that contains a specific note channel. This routine, in turn, calls the QT MIDI components to query them. NAGetMIDIPorts is the correct call for users to make. Users should not call QTMIDI .



 
extern pascal ComponentResult NASendMIDI(

                     NoteAllocator na,

                     NoteChannel noteChannel,

                     MusicMIDIPacket *mp)

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.
noteChannel: The function sends the packet to the synthesizer that contains this note channel. You obtain the note channel identifier from the NANewNoteChannel or the NANewNoteChannelFromAtomicInstrument function.
mp: The music packet to be sent.
function result: A result code.

DISCUSSION

The NASendMIDI function sends the MIDI music packet pointed to by the mp parameter to the synthesizer that contains the note channel identified by the noteChannel parameter. The na parameter specifies the note allocator instance to use.

NAGetNoteRequest

The NAGetNoteRequest function gets the note request passed to a note channel.



 
extern pascal ComponentResult NAGetNoteRequest(

                     NoteAllocator na,

                     NoteChannel noteChannel,

                     NoteRequest *nrOut)

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.
noteChannel: The note channel whose note request you want to get. You obtain the note channel identifier from the NANewNoteChannel or the NANewNoteChannelFromAtomicInstrument function.
nrOut: On exit, a note request structure Note Request Structure .
function result: A result code.

DISCUSSION

The NAGetNoteRequest function takes a note allocator instance in the na parameter and a note channel identifier in the noteChannel parameter. It returns, in the *nrOut parameter, the note request that was used to allocate the specified note channel.